docs(website): re-shoot the docs stills on the 0.69 UI, and make the rig reproducible - #828

git rm --cached was not enough: it left the files in the working tree, where the
next blanket `git add -A` re-staged them and silently undid the split. Removing
them from the tree on this branch is what actually holds.

They are committed on docs/media-v069 (#828), which is where #815 should take
them from — an asset and the reference to it belong in one PR, and whats-new.mdx
is on #815.

…830)

* docs(docs-media): document the rig contract, sidecars and the leak-pattern rule

* chore(docs-media): commit the rig launcher, seed and fixtures

seed.mjs and serve.sh existed only on one box and were full of its paths, ports
and process-manager specifics, which made tools/docs-media/ unusable by anyone
else. Both are now driven by PADDOCK_RIG_{HOME,CLONE,PROJECTS,FIXTURES}.

serve.sh was RETYPED from a spec rather than copied: the original held a live
OAuth token in plaintext, and a copy keeps the credential in the editor buffer
and in shell history. It carries no credential and cannot: it re-execs under
env -i, and the rig runs a fake claude on the batch runtime.

capture.mjs gains theme pinning via addInitScript (the appearance keys are read
by a pre-paint script, so writing them after goto shoots mid-swap) and the
provenance sidecars.

* docs(website): re-shoot the stale stills on the 0.67+ UI

Every UI-bearing image on the site predated the redesign, including the seven
committed the previous pass — those were merged 41 minutes before the first
design commit, so age was never the criterion.

Foundation dark at the out-of-box default (DEFAULT_APPEARANCE; paddock:theme
defaults to dark), which is what a reader sees on first boot. The theme quartet
is the deliberate exception: there the choice itself is the subject.

* docs(runbook): correct the 127.0.0.1 baseline split (39 docs + 7 README = 46)

The previous paragraph attributed all 46 to the docs subtree and then added
"plus 6 in README.md", summing to 52. A baseline that overcounts is how a
genuine new hit hides inside an expected one.

* docs(runbook): what a DESIGN release changes about a docs pass

Four things this pass proved the runbook lacked, all in section 5:

- The stale-build trap gets its own warning. Serving dist/ from a checkout
  that predates the release means every re-shot frame is the old UI, and it
  fails SILENTLY: rig up, seed passes, leak scan passes, every shot succeeds,
  md5sum clean. Recorded as a positive check against the SERVED BUNDLE — name
  a UI element only the new build can paint, then go and look at it — rather
  than against the git state of a directory.

- Bucket by the TENSE of the surrounding prose, not the directory. A What's
  New entry records a release as it shipped, so an old-UI frame there is
  correct and re-shooting it falsifies the archive; a current-behaviour page
  showing obsolete UI is simply wrong. Directory is a proxy that fails on
  exactly the dual-use assets cited from both — fork those.

- The rig's own fragility. A projects root on a non-persisted volume loses the
  whole tree on a restart while the data dir survives, so the instance boots to
  zero projects plus orphaned job records: it does not fail, it lies. Wipe both
  or neither, and commit the launcher and seed so the rig is reproducible.

- Appearance is no longer determined by the URL. Pin the theme with
  addInitScript (the keys are read pre-paint), clear the solved-accent cache,
  assert it applied, and never verify a theme by grepping CSS.

Plus the seeding race (rename in a second pass or the transcript's own title
resolution clobbers it) and the md5sum/framing discipline for near-identical
shots. Box paths, ports and domains are written as placeholders.

* docs(runbook): pinning the appearance, and seeding a rig with texture

Runtime themes mean a screenshot is no longer determined by the URL. The keys
are read by a pre-paint inline script, so a capture must write them with
addInitScript rather than page.evaluate after goto (which yields a mid-swap
frame), must clear the solved-accent cache (keyed theme:mode — a stale entry
paints the previous theme's accent pre-boot), and should assert it applied.
Never verify a theme by grepping CSS: OKLCH serialises as oklch(...) and the
accent token is a bare RGB triple, so a regex reader scores a themed build zero.

Also the seeding race: a chat is the product of a turn, so an API-only seed
photographs as an empty app; and renaming a chat immediately after the turn
completes loses to the transcript's own title resolution.

* docs(website): remove the whats-new stills from the captures PR

git rm --cached was not enough: it left the files in the working tree, where the
next blanket `git add -A` re-staged them and silently undid the split. Removing
them from the tree on this branch is what actually holds.

They are committed on docs/media-v069 (#828), which is where #815 should take
them from — an asset and the reference to it belong in one PR, and whats-new.mdx
is on #815.

* chore: drop the captures from this PR — they ship in #829

The stills were pushed onto this branch by a concurrent worker. This PR is the
rig and the tooling, which is code-shaped and independently reviewable; the
frames it produces are a separate review with separate criteria.

* docs(runbook): negative findings must be re-verified by the relaying party

The most valuable thing this pass produced. A wrong positive claim is caught by
the next reader; a wrong negative is acted on by DELETING the evidence — correct
prose is removed and it reads as diligence.

Happened twice within an hour in opposite directions over one file: the accent
picker's floor was reported unenforced (wrong — repairFill does repair derived
tokens at runtime), then over-corrected into "nothing is enforced" (also wrong),
neither time by anyone who opened accent.ts. The rule therefore binds the
corrector too, and negatives must be scoped to their narrowest true form.

Records the control that actually worked: the issue-filing child was told to
re-verify against main before filing, did, and its issues carry the narrow true
claim while the broken version was still circulating above it.

* docs: drop the runbook from this PR — #833 owns it

The same 216-line diff is in #833. Two open PRs editing one 760-line file
conflict on whichever merges second, and this PR is tooling: tools/docs-media/**
is independently reviewable and independently revertable without it.

* chore(docs-media): drop the manifest entry for a shot that ships nowhere

docs-discover.png was captured and deliberately not committed: the rig has no
discoverable Claude Code history, so the route renders its empty state. A
manifest entry for a frame that exists in no PR invites someone to go looking
for it.

The twelve remaining entries all ship — seven in #829 and five in #815. Those
five are NOT pruned despite having moved out of #829: they still ship, and the
manifest is the only record of which theme and solved accent each was shot at,
which is exactly what a reviewer of #815 needs.

* docs(docs-media): restore the README the rig PR is supposed to carry

Building this branch with 'git checkout <other-branch> -- tools/docs-media'
took the README from that branch too, silently reverting the rig-contract and
sidecar sections to main's 69-line version — so the PR shipped the scripts with
none of the documentation that makes them usable, which was half the point.

Also adds the staleness note: because each sidecar records the app version,
'is this frame stale after a repaint?' is a file read rather than an inspection
of every PNG.

* docs(docs-media): note the uniform-timestamp tell as a known seed improvement

seed.mjs creates its chats in one run, so every row in a capture carries the
same relative age — the v0.69 Home frame reads '2h ago' nine times. That is the
hand-seeded-fixture tell the runbook already warns about; a real instance has
this morning's work beside last week's.

The adoptable sessions already back-date their mtimes; the chats do not.
Recorded as a known improvement, not a fix: no committed frame is wrong because
of it.

* chore(docs-media): make HOME overridable, and actually forward it

On Discover the home path IS the content: DiscoverView renders {candidate.path}
and {result.homeDir} verbatim into <code>. So cropping fails (the path is the
subject), masking fails (the leak-masker would blank the element being shot),
and a symlink fails (paddock canonicalises for display). A rig whose HOME sits
under a scratch directory cannot produce a publishable Discover frame at all —
the shot is lost at launch, not at capture.

The override was inert as first written: env -i wipes the environment before the
re-exec, and PADDOCK_RIG_USER_HOME was not in the forwarding list, so the second
pass always fell back to the default. Same for PADDOCK_RIG_FIXTURES, which the
README documented and the launcher could never receive. Both now forwarded, and
verified with a control: without the override HOME resolves to <rig>/home, with
it to the path given.

Also documents the no-recorded-cwd exclusion — a staged transcript without a cwd
is dropped silently, which is the most common way a Discover seed fails while
looking like it worked.

* fix(docs-media): make HOME overridable, or Discover can never be shot

serve.sh hard-coded HOME to a scratch directory. On the Discover screen the home
path IS the content: DiscoverView renders {candidate.path} and {result.homeDir}
verbatim in <code>, with no truncation. So that rig cannot produce a publishable
Discover frame, and every escape is blocked — cropping loses the subject, the
leak-masker would blank the subject, and a symlink is defeated by paddock
canonicalising for display. The reason is in the comment because the reason is
what stops someone simplifying it back.

Also implements PADDOCK_RIG_FIXTURES, which the README documented and serve.sh
never had — so the committed fixtures.json was a dead file and the authored
replies never reached the fake claude. Both new vars are threaded through the
env -i re-exec; without that the override is scrubbed and silently does nothing.

Documents the other Discover trap: a staged transcript with no cwd is excluded
as no-recorded-cwd, which fails while looking like it worked.

---------

Co-authored-by: HomeLab Agent <homelab-infra@valfenda.net>